Design reads well, and the [main] / [contract] / [#4619] tagging makes the dependency story easy to follow. Two coherence issues surfaced reviewing this next to the compaction implementation (#4683):

§6 / Q4 numbers don't match what #4683 ships

The doc states bounded-size defaults of 64 attempt records / 128 spans / 8 KB string, "first+last-per-region." #4683 ships a default cap of 512, no span or byte cap, keyed on endpoint (not region). Per §4 rule 5 an FFI consumer would size a buffer to 64/128/8 KB and under-allocate ~8× on attempts (with no span/byte bound at all). Worth reconciling the numbers, or explicitly marking them as the target for the deferred engine rather than today's behavior.

"Deferred / OFF" vs. hard dependency

§0/§1/Q1 frame #4619 as a deferred optimization that stays OFF and "is not on main," but #4683 depends on #4619's DiagnosticsSummary (computed before compaction) and must merge after it. Read together the two statements look contradictory. A sentence clarifying "the contract doc doesn't depend on #4619, but the compaction impl in #4683 does" would resolve it.

§7.3 "one child span per attempt"

This becomes unrealizable once compaction elides the middle of a run (and §6 itself caps spans at 128). Might note that the per-attempt span mapping describes the uncompacted view, and a compacted run collapses to a single span + count.

Addressed in 60eeb5b (documentation only):

• §6 / Q4 numbers — reconciled with what Bound Cosmos diagnostics under retry storms #4683 actually ships. The per-attempt list is bounded by max_request_diagnostics (default 512, min 16), keyed on (region, endpoint, status, sub_status, execution_context) with first+last-per-run + exact aggregates + a bounded per-run rollup. The old 64/128/8 KB figures are now explicitly labelled as target defaults for the not-yet-implemented span/string representations and the deferred engine, the "64 attempt records" figure is marked superseded by the 512 default, and §4 rule 5 now tells FFI consumers to size off the configured cap rather than a hardcoded 64.
• Deferred / OFF vs hard dependency — added a note up front (§0) clarifying that this contract doc is standalone on main and depends on neither [Prototype] Diagnostics capture engine (Cosmos driver) #4619 nor Bound Cosmos diagnostics under retry storms #4683, while the Bound Cosmos diagnostics under retry storms #4683 compaction impl reuses [Prototype] Diagnostics capture engine (Cosmos driver) #4619's DiagnosticsSummary and must merge after it. So the "deferred / OFF / not on main" language (§1, Q1) describes the capture engine, not the compaction impl.
• §7.3 one-span-per-attempt — added a note that this is the uncompacted view; under compaction a run collapses to one span + a repeat count, so emitters build the tree from requests() (retained), not request_count().

markdownlint clean.

Addressed the round-2 doc nit in 5b5467147:

• Reconciled the per-representation caps: clarified that the shipped 512 structured-object record cap and the 128-span target are independent per-representation caps, not a single number that must agree. A span emitter reaches ≤128 spans by collapsing each run to one span + a repeat count (per §7.3), so span count tracks the number of runs (already cap-bounded), not retained records — 512 retained records still map to ≤128 spans.
• Noted PR Bound Cosmos diagnostics under retry storms #4683's new coherence guarantee in §7.3: the retained attempts and the per-run rollup are drawn from the same cap-bounded set, so an emitter never encounters a retained attempt whose run was omitted.

Documentation only.

Pushed e246b0d2f to address the review feedback and the documentation-only CI failures:

• Review comments (§6 + Q4): reworded the two "Shipped today (PR Bound Cosmos diagnostics under retry storms #4683)" claims to "Proposed in PR Bound Cosmos diagnostics under retry storms #4683 (not yet on main)", since max_request_diagnostics is added by the unmerged Bound Cosmos diagnostics under retry storms #4683 and isn't in diagnostics_options.rs on main (which only exposes max_summary_size_bytes / default_verbosity).
• Verify Links / Link verification check: the 5 broken relative ./src/... reference links are now absolute GitHub URLs. Verified locally with eng/common/scripts/Verify-Links.ps1 — no broken links.
• cspell (Build Analyze): added the doc's technical terms (flatbuffer, materializer(s), uncompacted, underspecified) to .vscode/cspell.json. cspell clean locally.

Build Pack Crates is a pre-existing, workspace-wide failure that this documentation PR doesn't introduce and can't fix: cargo package -p azure_data_cosmos_driver fails because the crate's azure_identity dev-dependency resolves to the unpublished 1.1.0-beta.1. The sibling code PR #4683 hits the identical Build Pack Crates failure. Adding the doc into the crate directory simply puts the crate in the "changed" set that triggers the pack step.

@NaluTripician ready to merge?

Superseded by #4789. The diagnostics contract/OpenTelemetry-mapping doc was corrected (real semconv names, handler-chain emission model, tail-based sampling, rate-limiting, and the [main] vs new-work tags fixed to reflect that the DiagnosticsContext foundation is already on upstream) and folded into #4789 as DIAGNOSTICS-CONTRACT.md alongside the implementation it describes. Closing this design-only prototype.